AgentKube-Kamaji

Introduction

AgentKube-Kamaji is a specialized agent within the Fulcrum Core ecosystem designed to manage Kubernetes tenant clusters through Kamaji. It serves as a bridge between Fulcrum Core's centralized management system and Kamaji's multi-tenant Kubernetes architecture, enabling seamless provisioning and lifecycle management of Kubernetes clusters.

The system enables organizations to:

Context

AgentKube-Kamaji operates within the broader Fulcrum ecosystem, serving as a specialized agent that connects Fulcrum Core to Kamaji for Kubernetes cluster management. The following diagram illustrates how AgentKube-Kamaji interacts with other components in the system:

graph TB FC((Fulcrum Core API)) AK[AgentKube-Kamaji] KP[Kamaji Parent Cluster] PX[Proxmox] subgraph Tenant Clusters TC1[Tenant Cluster 1] TC2[Tenant Cluster 2] TC3[Tenant Cluster 3] end FC -->|Deploy & Control| AK AK -->|Report Status & Metrics| FC AK -->|Manage TCPs| KP AK -->|Provision VMs| PX KP -->|Create & Manage| TC1 KP -->|Create & Manage| TC2 KP -->|Create & Manage| TC3

Components and Their Roles

AgentKube-Kamaji

AgentKube-Kamaji is a Fulcrum agent specialized in managing Kubernetes clusters through Kamaji. It:

Kamaji Parent Cluster

The Kamaji Parent Cluster is a Kubernetes cluster that hosts the control planes for tenant clusters. It:

Tenant Control Planes (TCPs)

Tenant Control Planes represent individual Kubernetes clusters managed by Kamaji. They:

Model

This section outlines the key entities in the AgentKube-Kamaji system and their relationships.

Class Diagram

classDiagram FulcrumAgent <|-- AgentKube : extends AgentKube --> KamajiClient : uses AgentKube --> ProxmoxClient : uses AgentKube --> JobHandler : uses AgentKube --> MetricsReporter : uses JobHandler --> KamajiClient : uses JobHandler --> ProxmoxClient : uses MetricsReporter --> KamajiClient : uses class FulcrumAgent { id : UUID name : string state : enum[New|Connected|Disconnected|Error|Disabled] tokenHash : string heartbeat() reportMetrics() pollJobs() } class AgentKube { vmManager : VMManager kamajiClient : KamajiClient proxmoxClient : ProxmoxClient updateVMResources() getVMStateCounts() getJobStats() } class KamajiClient { createTCP(name, spec) deleteTCP(name) updateTCP(name, spec) getTCP(name) listTCPs() getTCPStatus(name) } class ProxmoxClient { createVM(spec) deleteVM(id) startVM(id) stopVM(id) getVMStatus(id) getVMMetrics(id) } class JobHandler { processCreateJob(serviceId, spec) processDeleteJob(serviceId) processStartJob(serviceId) processStopJob(serviceId) processUpdateJob(serviceId, spec) pollAndProcessJobs() } class MetricsReporter { collectClusterMetrics() collectNodeMetrics() collectPodMetrics() report() } class VMManager { createVM(name, spec) deleteVM(id) startVM(id) stopVM(id) updateVMResources() getStateCounts() } class TenantControlPlane { name : string namespace : string version : string replicas : int serviceType : string port : int addons : map[string]object status : TCPStatus } class TCPStatus { phase : enum[Pending|Running|Failed] controlPlaneEndpoint : string conditions : Condition[] observedGeneration : int }

Entities

Core Components

  1. AgentKube

  2. KamajiClient

  3. ProxmoxClient

  4. JobHandler

  5. MetricsReporter

  6. VMManager

Kamaji Resources

  1. TenantControlPlane (TCP)

  2. TCPStatus

Architecture

AgentKube-Kamaji is built with Go, leveraging its concurrency model and performance characteristics to efficiently manage Kubernetes clusters. The system integrates with both Fulcrum Core and Kamaji to provide comprehensive Kubernetes management.

Architectural Layers

AgentKube-Kamaji follows a modular architecture organized into the following layers:

  1. Agent Core Layer

  2. Job Processing Layer

  3. Kamaji Integration Layer

  4. VM Management Layer

  5. Metrics Collection Layer

Deployment Architecture

AgentKube-Kamaji is typically deployed alongside a Kamaji parent cluster, with access to both Fulcrum Core and Proxmox. The deployment architecture follows this pattern:

  1. Kamaji Parent Cluster

  2. AgentKube-Kamaji

  3. Proxmox Cluster

Workflow Diagrams

Tenant Cluster Creation Workflow

sequenceDiagram participant FC as Fulcrum Core participant AK as AgentKube-Kamaji participant KC as Kamaji API participant PX as Proxmox API FC->>AK: Create Kubernetes Cluster Job AK->>AK: Process Job Parameters AK->>KC: Create Tenant Control Plane KC-->>AK: TCP Created AK->>PX: Provision Worker Node VMs PX-->>AK: VMs Created AK->>KC: Get TCP Connection Info KC-->>AK: TCP Endpoint and Credentials AK->>PX: Configure VMs as Kubernetes Nodes PX-->>AK: VMs Configured AK->>KC: Verify Cluster Health KC-->>AK: Cluster Status AK->>FC: Report Job Completion Note over AK,FC: Include TCP Endpoint and Credentials

Tenant Cluster Monitoring

sequenceDiagram participant AK as AgentKube-Kamaji participant KC as Kamaji API participant PX as Proxmox API participant FC as Fulcrum Core loop Every Metric Interval AK->>KC: Get TCP Status KC-->>AK: TCP Status Data AK->>KC: Get Cluster Metrics KC-->>AK: Cluster Metrics Data AK->>PX: Get VM Resource Usage PX-->>AK: VM Resource Data AK->>AK: Process and Normalize Metrics AK->>FC: Report Metrics FC-->>AK: Acknowledge end

Implementation Details

Agent Integration with Fulcrum Core

AgentKube-Kamaji integrates with Fulcrum Core using the standard agent interface, which includes:

Kamaji Management

The agent manages Kamaji Tenant Control Planes through the Kubernetes API, using:

Proxmox VM Management

For managing virtual machines on Proxmox, the agent:

Configuration and Customization

AgentKube-Kamaji supports various configuration options:

Conclusion

AgentKube-Kamaji extends Fulcrum Core's capabilities to manage Kubernetes clusters using Kamaji's multi-tenant architecture. By leveraging both Kamaji for Kubernetes management and Proxmox for infrastructure provisioning, it provides a comprehensive solution for deploying and managing Kubernetes at scale.

The integration with Fulcrum Core enables consistent management across different service types, while the specialized Kubernetes and VM management capabilities ensure efficient operation of tenant clusters. This combination makes AgentKube-Kamaji a powerful tool for organizations that need to provision and manage multiple Kubernetes environments through a unified interface.